Hello there. This is the Read Me file for SquidGirlCleaner, version 2019-12-15.


+---------------------------------+
| What is SquidGirlCleaner (for)? |
+---------------------------------+

SquidGirlCleaner is a batch script, meant to perform some kind of "cleaning".
It is NOT a general purpose cleaning tool, but has a specific focus: it is meant to determine which files, in Windows' "Installer" folder, should not be needed any more, because of either of the following reasons:
 - they are related to superseded patches (that is, patches that were made obsolete by installing newer ones)
 - they are neither the installer for a currently installed product nor a patch for one of those products - I call these "orphan" files


+-----------------+
| /!\ WARNING /!\ |
+-----------------+

WARNING: using SquidGirlCleaner could cause issues when trying to further update, repair or uninstall programs, and there certainly are safer options you may want to try to free up space before resorting to this. It is also very likely to prevent you from removing patches.
You should only use this script if you don't mind taking those risks.


+-------------------+
| How does it work? |
+-------------------+

To perform its task, the script reads (from the registry) information about programs (or "products") that are installed on the system, and the patches that have been applied to them.

There, both the products and their patches have unique identifiers called "SQUIDs" (short for "SQuished gUID" , cf. https://support.microsoft.com/en-us/help/976220/ ... this explains part of the script's name).

While reading those pieces of informations, the script populates a listing of all Patches, which product they apply to, and their current "State", as well as a list of "Known Files" (both from patches and product installers). 

Then, it attempts to determine which patch files aren't needed any more: it should be those with their "State" value set to "2", as long as they have that same state for all products they apply to.
For such patches, both their main .msp file and associated registry keys are added to yet another listing file, "Removable Things.csv", refered to by the TBD variable within the script and henceforth.

Once this is done, the script also has a look at the list of all .msi and .msp files found within the Windows Installer folder: any of the files there which do not appear in the list of Known Files is considered an "orphan" file, and also added to "TBD": since no reference to it was found within the registry, it is assumed to be a leftover of a failed/aborted (un)installation.


+------------------+
| How do I use it? |
+------------------+

First, make sure you have read the license and agree to its terms.

Then, you may run the script "as an administrator", and press a key to confirm that you agree with the license agreement and know what you are doing.

By default, the script will attempt to create 2 folders:
 - "%userprofile%\desktop\%computername%.SGC", where it'll place its logs and work files
 - "%userprofile%\desktop\%computername%.SGC_Backup", where it'll move the files it considers to be "unneeded" as well as registry backups and a script to allow for reverting the changes.

Warning: using that "undo" script may also cause issues if you do so after some more updates were installed!


+--------------------------------------------------+
| "Advanced" usage: what if I want to automate it? |
+--------------------------------------------------+

If you really want to, the script supports running in unattended mode using the following syntax:
   SGC mode_command ["logs folder" ["backup folder"]]
 
Note: you cannot specify a backup folder unless you first specify the one for logs.
However, if you don't care where the logs are stored, using "" for the logs directory will have it default to "%userprofile%\desktop\%computername%.SGC"

Possible values for the mode_command are:

 /analyse (aliases: /report ; /survey ; /checkonly): "Analyse" mode
The script will perform an analysis and generate its usual work/log files, but should not attempt to delete or move any file.
This way, you can examine the logs before you decide if you want to take the risk of actually running the script in either Move or Delete mode.
Warning: you'll need to either specify a different folder for the logs if you want to run the script a second time, or rename/move/delete the previous logs folder

 /move (aliases: /unattended ; /passive): "Move" mode.
Pretty much the same as running the script without parameter, but specifying the Move mode from the command line allows to run unattended, and of course to change the logs/backup folders from the command line, thus without having to edit the script's code.

 /delete (aliases: /brutal ; /yolo ; /purge ; /cleanse): sets the script to "Delete" mode.
We take no prisoners, there will be no way to revert the changes.
Only use that mode either if you have ABSOLUTE faith that the script works flawlessly, or if it REALLY doesn't matter that it may cause issues.
Don't come crying if it breaks anything (see the License).


+------------+
| Exit codes |
+------------+

If you run the script in unattended mode on remote systems (o_O), you may want to know what its exit codes mean, especially if it fails without producing logs.
Below are the possible values and their meaning for the version mentioned at the beginning of this file:

0 : script ran without error (or failed to notice them). There still may be warnings in the logs, but (hopefully) nothing to worry about.
1 : one or more errors occurred. Logs should exist, and checking them might give you hints about what went wrong.
2 : the Logs folder already existed before the script was ran. To avoid overwriting stuff or making mistakes due to data already being there, the script won't work or even produce logs in these circumstances.
3 : same as 2 except it's about the Backup folder
4 : failed to create the Logs folder
5 : failed to create the Backup folder
255 : the script was called with an invalid parameter
